Subject: SNA Service Transaction Program Names

From: "John E. Fetvedt (919-254-4366)" <[email-masked]>
Date: Fri, 24 Mar 95 09:27:37 EST

CIW General,

     Attached is the updated proposal to handle SNA Service Transaction
program names.  Please review it for completeness and send me any
comments or corrections by Friday, April 14th.  This will allow us to
make any last minute corrections before the May CIW.

     Thanks for your prompt attention.

     Cheers.

John Fetvedt

----------------------------- Referenced Proposal ---------------------------

Status:
-------

     The work item "Service TP Support" received Approved Direction (AD)
status at the 10/94 CIW.

     The CIW Technical Plan schedule proposes that Approved Pages (AP)
and Closed Pages (CP) status be granted at the 5/95 CIW.

Requirements:
-------------

     1. Allow a client program to specify an SNA Service Transaction
        name for its partner program's TP name.

     2. Allow a program to associate an SNA Service Transaction name
        with itself.

Problem:
--------

     1. CPI-C 2.0 defines the TP_name as a T61String.  A T61String does
        not include the EBCDIC characters X'00'-X'3F', which are used in
        the first character of an SNA Service Transaction name.

     2. CPI-C 2.0 states the TP_name will be automatically converted
        from the local system's native encoding to the transfer encoding
        where necessary.  However, the conversion, either to or from,
        the EBCDIC characters X'00'-X'3F', used in SNA Service
        Transaction names, is not defined.

Proposal:
---------

     Define new, specific encoding/decoding rules for the automatic
conversion of the TP_name field, when the field starts with a straight
single quote character.

     If the field starts with a straight single quote character, it must
also:

          1) contain a second straight single quote character,

          2) contain a non zero, even number of characters between the
             straight single quote characters

          3) contain only the characters 0-9, a-f, and A-F between the
             straight single quote characters (upper and lower case are
             equivalent).

     If the field starts with a straight single quote character and
     fails to satisfy any of the above rules, the call will be failed
     with a CM_PROGRAM_PARAMETER_CHECK return_code.

     *  When a TP_name field is received from the application,
             -  Release_Local_TP_Name
             -  Set_TP_Name
             -  Specify_Local_TP_Name
        any characters within the straight single quote characters are
        treated as hex representation and not subject to data conversion
        from the native encoding to EBCDIC, and any characters following
        the second straight single quote character are to be converted
        when appropriate.

     *  When a TP_name field is returned to the application,
             -  Extract_TP_Name
        any TP_name containing one of the special characters used in
        SNA Service Transaction names (X'00'-X'0D' and X'10'-X'3F') in
        the first character of the name, will be returned in hex
        representation between paired straight single quote characters,
        e.g. '21F0F0F6'.

     Note that a CPI-C implementation on an EBCDIC platform, that may
not currently look at the TP_name field because no automatic conversion
is required, would now need to check the field for a leading straight
single quote character and convert any hex encoding appearing between the
straight single quote characters.

Specific changes:
-----------------

1. Chapter 2, Automatic Conversion of Characteristics:

   Add the following text to the TP_name entry in the list at the end of
   the section:

   "(Refer to Appendix D, SNA Service Transaction Programs, for special
    handling of SNA Service Transaction Program names.)"

2. Chapter 4, Extract_TP_Name (CMETPN), Usage Notes:

   Add a new Usage Notes:

   "n. TP_name will be returned using the local system's native
       encoding.  CPI Communications automatically converts the TP_name
       from the transfer encoding where necessary.

   "n. Refer to Appendix D, SNA Service Transaction Programs, for
       special handling of SNA Service Transaction Program names."

3. Chapter 4, Release_Local_TP_Name (CMRLPN), Parameters:

   Add a note under TP_name:

   "Note: Refer to Appendix D, SNA Service Transaction Programs, for
       special handling of SNA Service Transaction Program names."

4. Chapter 4, Set_TP_Name (CMSTPN), Parameters, TP_name:

   Change the first sentence in the note under TP_name from "... may
   require special authority ..." to "may require special syntax for
   the name and special authority ...".

5. Chapter 4, Set_TP_Name (CMSTPN), Usage Notes:

   Add a new Usage Note:

   "n. Refer to Appendix D, SNA Service Transaction Programs, for
       special handling of SNA Service Transaction Program names."

6. Chapter 4, Specify_Local_TP_Name (CMSLPN), Parameters:

   Add a note under TP_name:

   "Note: Refer to Appendix D, SNA Service Transaction Programs, for
       special handling of SNA Service Transaction Program names."

7. Appendix D, "SNA Service Transaction Programs":

   a) Add the following between the first and second paragraphs:

      "Therefore, whenever an SNA Service Transaction program name is
       used as an input parameter on a CPI Communications call, the
       first character must be enclosed between straight single quote
       characters.  CPI Communications will parse the TP_name field
       using the rules:

          1) The name must contain a second straight single quote
             character.

          2) The name must contain a non zero, even number of
             characters between the straight single quote characters

          3) The name may contain only the characters 0-9, a-f, and A-F
             between the straight single quote characters (upper and
             lower case are equivalent).

      "If the name starts with a straight single quote character and
       fails to satisfy any of the above rules, the call will be failed
       with a CM_PROGRAM_PARAMETER_CHECK return_code.

      "When a TP_name field is received from the application,
             -  Release_Local_TP_Name
             -  Set_TP_Name
             -  Specify_Local_TP_Name
       any characters within the straight single quote characters are
       treated as hex representation and not subject to data conversion
       from the native encoding to EBCDIC, and any characters following
       the second straight single quote character are to be converted
       when appropriate.

      "When a TP_name field is returned to the application,
             -  Extract_TP_Name
       any TP_name containing one of the special characters used in
       SNA Service Transaction names (X'00'-X'0D' and X'10'-X'3F') in
       the first character of the name, will be returned in hex
       representation between paired straight single quote characters,
       e.g. '21F0F0F6'."

   b) Delete the note (last paragraph), "Note: Because of the special ...
      in the side information.".

--------------------------- end of proposal ----------------------------